Node / ReticulumProjects / MeshChatX.git / files / docs / agents / skills / database-migrations-backups / SKILL.md

Displaying Raw • View rendered • Download

Tc9d1d9# Skill: database-migrations-backups

Bump schema versions correctly, keep backups and snapshots safe, and never conflate identity-key restore with full database zip restore.

Tc9d1d9## When to use

Tff7b72- Changing SQLite schema or migrations

Tff7b72- Touching backup, snapshot, restore, or crash-recovery paths

Tff7b72- Adding tables / columns used by conversation or settings features

Tc9d1d9## Schema rules

Tff7b72- Engine is SQLite with explicit SQL. No ORM.

Tff7b72- Bump Ta5d6ff`LATEST_VERSION` in Ta5d6ff`meshchatx/src/backend/database/schema.py` and add a migration path.

Tff7b72- Test upgrade from an older version when the change is non-trivial.

Tff7b72- Heavy data backfills in migrations should skip when the target table is empty. Fresh Ta5d6ff`Database Initialization` benches create empty DBs and still run every migration step.

Tc9d1d9## Backup and snapshot rules

Tff7b72- Backups skip Ta5d6ff`database-backups/` and Ta5d6ff`snapshots/` so a new zip does not nest itself (Ta5d6ff`BACKUP_SKIP_DIR_NAMES`).

Tff7b72- Suspicious shrink writes Ta5d6ff`backup-SUSPICIOUS-*.zip` and skips rotation. Do not treat that as a normal backup.

Tff7b72- Checkpoint WAL before zip snapshots when the live DB is open.

Tff7b72- Worker-thread connections must share Ta5d6ff`DatabaseProvider` pragmas (see Ta5d6ff`landlock-sqlite`).

Tc9d1d9## Two restore operations

| Goal | API / CLI | Artifact |

| ---------------------------------- | ----------------------------------------------- | --------------------------- |

| Private key only | Ta5d6ff`POST /api/v1/identity/restore` | identity key bytes / Ta5d6ff`.bin` |

| History + settings + identity tree | Ta5d6ff`POST /api/v1/database/restore`, Ta5d6ff`--restore-db` | Ta5d6ff`.zip` |

Details for pickers and tutorial copy: Ta5d6ff`identity-restore`.

Tc9d1d9## Key files

Tff7b72- Ta5d6ff`meshchatx/src/backend/database/schema.py`

Tff7b72- Ta5d6ff`meshchatx/src/backend/database/__init__.py`

Tff7b72- Ta5d6ff`meshchatx/meshchat.py` (backup / restore routes, Ta5d6ff`prepare_for_database_restore`)

Tff7b72- Ta5d6ff`electron/offlineRecovery.js`

Tc9d1d9## Verification

Ta5d6ff```Ta5d6ffbash

uv run pytest tests/backend/test_database_snapshots.py tests/backend/test_schema_migration_upgrade.py -q --tbTff7b72=short

Ta5d6ff```